User Guide to the Modula-2 System
---------------------------------

Table of Contents

4.     MODULA-2 Compiler, Linker, Debugger
4.1.   A User Guide to the MODULA-2 System
4.1.1. Glossary and examples
4.1.2. (** The M3 MODULA-2 base **)
4.1.3. Compiling
4.1.4. Linking
4.1.5. Running a program
4.1.5A   Call by command interpreter
4.1.5B   overlay organization
4.1.5C   call from a program
4.1.5D   run time support for program management
4.1.5E   (** converting from .LOD to .IMA format **)
4.1.6. Debugging
4.1.7. Library Searching Strategies
4.1.8. The module SYSTEM
4.1.8A Workfiles
4.1.8B Commandfiles
4.1.8C History (Acknowledgements)
4.1.9. Compiler error messages



(MODLIB:GUIDE.TEXT    23.04.85)

4. MODULA-2 Compiler, Linker, Debugger
--------------------------------------

adapted by Institut fuer Elektronik.
Version 5.8.1983, prepared by P. Fink ETH Zuerich.


In diesem Kapitel erklaeren wir detailliert die
MODULA-2 Programmierumgebung . Da viele der Prinzipien
des PDP-11 MODULA gelten, wurde die Originaldokumentation "A
User Guide to the MODULA-2 System" als Grundlage gewaehlt
(in englischer Sprache).

(* parts which are not valid for the portable MC68000 Compiler,
   have been put into comment brackets by P. Fink.(**...**)
   Some remarks about the SMAKY8 have been added when necessary
*)


4.1 A User Guide to the MODULA-2 System
---------------------------------------

The Modula system consists of a compiler, a linker, a debugger
and possibly some support utilities.
the compiler and linker are themself modula programs.
On the SMAKY 8, a modula program is simply called by
typing
  X progname     in the CLE line.

Therefore, the compiler is called by
  X modula
.
The linker is called by
  X linker
.

A program may be stopped with the CLEAR key on the numerical
pad. This works almost anytime, except in tight loops.
The CLEAR key is checked on every system request.
(**
MODULA-2/68K is a resident programming environment for
MODULA-2 that runs on the MC68000 based "M3" system. The
software consists of a compiler, a linker, a debugger and
utility modules, which are all linked to the operating
system.

The operating system first gives control to the command
interpreter,  which accepts  the  file  name of the next
program to be executed. The command interpreter then terminates
and calls the loader,  which  is also embedded  in  the
operating system. It loads the named file and transfers
control to  that  program. Upon  termination  of  the
program, control returns to the operating system, and the
command interpreter asks for the next program. In an error
situation control returns to the operating system, too. The
exception handling part has to correct the system state (e.g.
correct the stack pointer). Therefore at the command
interpreter level the system is always in a consistent state.
**)
Compiler, linker, and debugger are Modula-2 programs.  They
are treated by the operating system like any other user program.


The following chapters require a sound knowledge of the
language itself.

Reference literature:

     N.Wirth: Programming with  MODULA-2, Springer Verlag.


4.1.1. Glossary and examples
----------------------------

compilation unit  : Unit accepted by compiler for compilation,
                    i.e. definition module or program module
                    (see Modula-2 syntax).
definition module : Part  of  a separate module specifying the
                    exported objects.
program module    : Implementation  part  of a separate module
                    or main module.
source file       : Input  file  of  the compiler (compilation
                    unit) (default extension MOD).
symbol file       : Compiler  output  file  with  symbol table
                    information; information generated  during
                    compilation   of   a   definition   module
                    (default extension SYM).
reference file    : Compiler   output   file   with   debugger
                    information, generated during  compilation
                    of  a  program  module  (default extension
                    REF).
link file         : Compiler output file with code in Modula-2
                    linker format (default extension LNK).
load file         : Linker  output  file with code in Modula-2
                    loader format (default extension LOD).
map file          : Linker  output  file  with  storage layout
                    information (default extension MAP).

(* system dependent definitions: specific for the SMAKY 8 *)

filename          : File names are at most 11 characters long
                    (plus device, plus extension). When a module
                    name is longer, then its corresponding filename
                    is truncated to 11 characters.

default device    : a device name needs not to be specified on
                    the SMAKY 8.

default extension : when a filename doesnt contain an extension
                    or is terminated with a point, then this
                    default extension is appended to the name

default libraries : on the SMAKY8, the default libraries searched
                    are the directory of the source file, then
                    <empty>, i.e. #MM0:, and then MODLIB:



Examples:
---------

The following examples are used in the description:


  MODULE Prog1;
    ...
  END Prog1.


  MODULE Prog2;
  BEGIN
    a := 2
  END PROG2.


  DEFINITION MODULE Prog3;
    EXPORT QUALIFIED ...
    ...
  END Prog3.

  IMPLEMENTATION MODULE Prog3;
    ...
  END Prog3.


  DEFINITION MODULE Prog4;
    IMPORT SystemTypes;
    EXPORT QUALIFIED ...
    ...
  END Prog4.

  IMPLEMENTATION MODULE Prog4;
    IMPORT SystemTypes, Loader, Exceptions;
    ...
  END Prog4.


  MODULE Prog5;
    IMPORT Prog3, Prog4;
    ...
  END Prog5.


(**
4.1.2 The M3 MODULA-2 base
--------------------------

The operating system is loaded and started when the M3 system
is booted (e.g. after GO23000).

Immediately  the command interpreter is executed. The
command interpreter displays the prompt symbol "->" to
indicate that it waits for a command (which can result in a utility
program call).

Normally a user program can be interrupted by twice <ctrl>C;
then control returns to the operating system.
**)
4.1.3 Compiling
---------------

Compilation of a program module:
--------------------------------
The compiler is  called  by  typing  X  MODULA, in the CLE line.
After displaying  the  string  "source file>" the compiler
is ready to accept the filename of the 'compilation unit' to
be compiled.

Default device    : --

Default extension : MOD


  ->X MODULA<cr>
  source file> PROG1<cr>     (* name PROG1.MOD is assumed*)
  p1
  p2                         (* indicates succession of   *)
  p3                         (* activated compiler passes *)
  p4
  p5
  end compilation
  ->

If  syntactical  errors  occur in the compiled unit,
compilation stops after the third pass and a listing with
error messages  is generated:

  ->X MODULA<cr>
  source file> PROG2<cr>
  p1
   ---- error                 (* error detected by pass 1 *)
  p2
  p3
   ---- error
  lister
  end compilation
  ->



Compilation of a definition module:
-----------------------------------
For  definition  modules   the   filename   extension   DEF
is recommended.  The  definition  part of a module must be
compiled prior to its implementation part. A symbol file is
generated for definition modules.



  ->MODULA<cr>
  source file> PROG3.DEF<cr>  (* definition module *)
  p1
  p2
  symfile
  lister
  end compilation
  ->



Symbol files needed for compilation
-----------------------------------
At  the  compilation  of  a  definition  module,  a  symbol
file containing  symbol  table  information  for  the
compiler   is generated.  This  information  is  needed by
the compiler in two cases:

-  At compilation of the implementation part of the module.

-  At compilation of another unit, importing  objects  from
   this separate module.

According  to  a  program  option  set  at  the beginning of
the compilation (Q option), the compiler asks for the
needed symbol  files  or  attaches  them by a default name
(the first n characters of the module name, see glossary).
  ->X MODULA<cr>
  source file> PROG3<cr>      (* implementation module *)
  p1
   Prog3: DK:PROG3.SYM
  p2
  p3
  p4
  p5
  end compilation
  ->

  ->X MODULA<cr>
  source file> PROG4.DEF/QUERY<cr>
  p1
   SystemTypes> SY:SYTY<cr>
  p2
  symfile
  lister
  end compilation
  ->

  ->X MODULA<cr>
  source file> PROG5/QUERY<cr>
  p1
   Prog3> PROG3<cr>
   Prog4> PROG4<cr>
  p2
  p3
  p4
  p5
  end compilation


    X MODULA
   source file> PROG6/L
  library prefixes> D:,XY:
   p1
   .....
  ->



Files generated by the compiler:
--------------------------------
Several files are generated by the compiler. They all obtain
the same device:filename as the source file with the following
extensions:

  for definition modules :  listing         *.LST
                            symbol file     *.SYM

  for program modules    :  listing         *.LST
                            reference file  *.REF
                            code file       *.LNK



Program options for the compiler
--------------------------------
When reading the source file name,  the  compiler  also
accepts some  program  options from keyboard. Program
options are marked with a leading character '/'  and  must
be  typed  sequentially after the file name.

The compiler accepts the options:

/QUERY    : Compiler  explicitly  asks  for  the  names of
            the needed symbol files belonging to modules
            imported by the compiled unit.
            /Q is a short form for this option.

/NOQUERY  : No query for symbol  file  names.  The  files
            are searched  corresponding to a default
            strategy.

/LISTING  : A listing file must be generated.
            /LIST is accepted for this option.

/NOLISTING: No listing file must be generated.
            /N is a short form for this option.

/EL       : A listing will only be generated when there are
            compilation errors.
            Note all errors are also displayed on the terminal.

/VERSION  : Compiler has  to  display  information  about  its
            version.
            /V is a short form for this option.

/LIBQUERY : library query: the compiler has to ask for the libraries
            it should search when looking for symbol files.
            Up to 5 user libraries may be specified, separated by comma.
            Note: <empty> and MODLIB: are always searched in addition to
            these 5 libraries and need not to be specified.
            Normally, the directory of the source file, <empty> and
            MODLIB: are searched.
            /L is an abbreviation for /LIBQUERY.


/LARGE    : Large program option. Normally the compiler allocates tables and
            files for a small to medium sized program. This option forces
            it to allocate large tables and files.
            /LA is an abbreviation for /LARGE.



Defaults:

*  NOQUERY and EL are set as default options.


Compilation options in compilation units
----------------------------------------

Comments in a Modula-2 compilation unit may be used  to
specify certain compilation options for tests.

The following syntax is accepted for compilation options:

  Options = Option { "," Option } .
  Option  = "$" Letter Switch .
  Switch  = "+" | "-" | "=" .

Options  must be the first information in a comment clause.
They are  not  recognized  by  the  compiler,  if  other
information preceedes the options in the clause.

Options :

  T   Array index and case label boundary test.
  S   Stack overflow test.
  P   No generation of procedure entry and exit code.
  C   CLR option. C- means the compiler must not generate CLR instructions.

Switches:

  +   Test code is generated.
  -   No test code is generated.
  =   Previous switch becomes valid again.

Defaults :

  All switches are set to "+" by default.

Example :

  MODULE x; (* $T+ *)
    ...                           test code generated
    ...
    (*$T- *)
    a[i] := a[i+1];               no test code is generated
    (*$T= *)
    ...                           test code is generated
    ...
  END x


Remark concerning the C option:
  This option is useful when writing device drivers.
  Since the CLR instruction of the MC68000 does a READ/WRITE cycle, it should
  not be generated for absolute variables which are device registers (e.g.
    UADATA [300h]: CHAR;) When such a variable is passed to a procedure
  as an argument, then within the procedure, the compiler doesn't know it
  is an absolute variable and may erronously generate the CLR instruction.
  With C- in the procedure, it is instructed to generate a MOVE #0,...
  instead.


Module key:
----------

To each compilation unit the  compiler  generates  a  so
called "module  key".  This  key is unique and is needed to
distinguish different compiled versions of the same module.
The  module  key is written on the symbol file, the link
file and the load file.

For an implementation module no new key is generated. It
gets the same key as  the  definition  module.  The  module
keys  of imported  modules  are also recorded on the symbol
files and the link files.

Any mismatch of module keys belonging to the  same  module
will cause an error message at compilation or link time.

CAUTION : Recompilation  of  a  definition module will
          produce a new symbol file with a new module key.
          In  this  case the implementation module and all
          units importing this module directly or indirectly
          must be recompiled.

          Recompilation of an  implementation  module  does
          not affect the module key.



Differences and restrictions in implementation:
----------------------------------------------

For the implementation of Modula-2 for MC68000-based computers
some differences and restrictions must be considered.

FOR statement
-------------

The control variable must not be of type CHAR or any
enumeration type (byte size), if step is not -1, or 1.

The step must not be greater than 77777B.

CASE statement
--------------

The labels of a case statement must not be greater than
77777B.

Dynamic arrays
--------------
In a procedure declaration, only the form    VAR  ARRAY OF <anytype>   is
available, but not  ARRAY OF <anytype>   .

For this reason, the compatibility rules between formal and actual
parameters have been lowered for VAR ARRAY OF CHAR and VAR ARRAY OF WORD:
- strings are considered compatible with VAR ARRAY OF CHAR.
- everything is compatible with VAR ARRAY OF WORD.

Type Transfer Functions between types of unequal size
-----------------------------------------------------

The type transfer functions to a shorter size (e.g. CHAR(cardinal)) transfer
the lower order bits of the source. Type transfers to a longer size
transfer the 'value'. For unsigned source types, zeroes are filled into the
higher bits (e.g. ADDRESS(char), ADDRESS(cardinal)). For a signed source type,
the sign is extended (e.g. ADDRESS(integer));


PROCESS, NEWPROCESS, TRANSFER, IOTRANSFER, LISTEN, SYSRESET,
module priorities.
------------------------------------------------------------

These language concepts for concurrent processing are implemented.
SMAKY 8 notes: The implementation assumes the tasks are running
in User Mode. All processes are part of the same NTREL task.
PROCESS, NEWPROCESS and TRANSFER may be used freely, even for
structuring application programs.
Before using IOTRANSFER (which handles peripheral interrupts),
it is recommended to consult the actual implementation listings.
IOTRANSFER may interfere with the operating system PSos.





Compatibility with SMILERX V4
-----------------------------
Symbol Files and Link Files produced by SMILERX V4 are acceptable when
transferred properly from a CYBER to the SMAKY 8 and converted.



MC68000 Modula-2 compiler profile
---------------------------------

INTEGER  :   -32768..32767
CARDINAL :   0..65535
ADDRESS  :   0..4294967295
REAL     :   -3.4028232E38..-1.1754943E-38, 0.0,
             +1.175494E-38..+3.4028232E38  (IEEE 32-bit Format)

Max. Index : -32768..65535
Max. Range : 32767

ARRAY size      : 32766 max.
RECORD size     : 32766 max.
Global Variables: 32766 max.


Allocation of Modula-2 types:

BOOLEAN  :                Byte (1)
CHAR     :                Byte (1)
INTEGER  :                Word (2)
CARDINAL :                Word (2)
REAL     :                Long (4)
WORD     :                Word (2)
ADDRESS  :                Long (4)
BITSET   :                Word (2)
pointer  :                Long (4)
enum. ( <= 256 elem. ) :  Byte (1)
enum. ( >  256 elem. ) :  Word (2)
set   ( <= 8 members ) :  Byte (1)
set   ( >  8 members ) :  Word (2)

            
4.1.4 Linking
-------------

Compiler code output files (called  link  file,  with
extension LNK)  must be linked before run time. One or more
link files can be linked to a program. The generated  code
file  (called  load file, with extension LOD) may be loaded
by the loader.

Call  the  linker  by typing X LINKER in the CLE line. After
displaying the string "master file>" the linker  is  ready
to  accept  the filename of the master file (main program).

  ->X LINKER<cr>
   master file> PROG1<cr>     (* PROG1.LNK is assumed *)

The linker generates two files with the same name as the
master file and the following extensions:

  LOD  : Load file with code to be loaded.
  MAP  : Map with allocation addresses of linked modules
         (only when program option M is set).

A  program (overlay) may  be  linked  to an already linked
base. Information about this base is needed by the linker.
To get this information,  the  linker has to attach the load
file (extension LOD) of this base.

(**
Normally the base is the resident part of the  basic
executive. The  file SY:MODULA.MXS is the default base file
attached by the linker, if no other base file is specified
(see  program  option B).
**)

All  separate  modules  imported  by the master module (or
other linked modules) must be  linked.  If  a  needed
module  is  not already  linked (e.g. in the base), then the
linker requests the corresponding link file. To search this
file a default  strategy or a query strategy can be chosen
(see program option Q).
There is also an option the change the libraries for
searching (see option /L)

When reading the name of the master file the linker also
accepts some program options from keyboard. Program options
are  marked with  a  leading  character  '/'  and must be
typed sequentially after the file name.

The linker accepts the options:

/B    : Linker has to ask for the name of the base file.

/Q    : Linker  has  to  ask  for  the  names  of  link  files
        belonging to imported modules. If Q is not set, then the
        files are searched corresponding  to a default
        strategy.

/L    : Linker has to ask for the names of the libraries to be
        searched. Up to 5 user libraries may be specified, separated
        by comma. In addition to these libraries, <empty> and MODLIB:
        will always be searched when looking for imported modules.
        Normally, the directory of the master file, <empty> and MODLIB:
        are searched.

/M    : A map file must be generated.

/D    : Drop Tables Option: The Linker is inhibited from writing certain 
        information to the load file. The load file becomes shorter. The 
        following two tables are omitted, and the consequences are:
        a) the Linker Tables. Overlays cannot be linked above this program.
        b) the Debugger Tables. The symbolic Debugger cannot be used for
           this program (unless linked again without the /D option).

/V    : Linker  has  to  display  information  about  its version.

(**S     : System  will  be  generated,  i.e. there is no base to
        link to it.

A     : Use only with option S.
        Linker  has  to  ask for the start (lowest) address of
        the new generated system.
        If  A  is  not  set  then  a  default value (40000H) is
        substituted to the start address.
  **)

->X LINKER<cr>
 master file> PROG4/Q<cr>   (* base is the operating system  *)
 end linkage                 (* imported modules are already *)
->                           (* linked in the resident part  *)

->X LINKER<cr>
  master file> PROG5/B/Q/M<cr>
  base file> PROG4<cr>        (* DK:PROG4.LOD is accepted *)
   files linked:
  Prog3> PROG3<cr>            (* DK:PROG3.LNK is accepted *)
 end linkage                  (* DK:PROG5.MAP is generated *)
->



4.1.5 Running a program
-----------------------

A  linked  program  is  ready  to  be  called  (i.e.  loaded
and executed). There are  two  different  possibilities  to
call  a program:

- pass a file name to the command interpreter.
- activate the procedure Call, exported from module SM8Loader.
  (by a program)


(**
4.1.5A Call by command interpreter
----------------------------------

A program linked to the resident part  of  the  basic
executive (MODULA.MXS)  is  called  by passing its filename
to the command interpreter.  After  displaying  an  "->" the
command interpreter is ready to accept a file name.

For the search strategy refer to (2.2.2 Utility-Programme).

If an error occurs during loading or execution, then the
command interpreter  displays  an  error  message. If enabled,
a dump of the core image will be written on file SY:DUMP.COR
after an execution-error.
(refer to 2.1.2 Command DON/DOFF)


->PROG1.LOD<cr>              PROG1.LOD is loaded and executed
...
->PROG5.LOD<cr>
---- wrong load key     program not linked to operating system
->
**)


4.1.5B Overlay organisation:
---------------------------

A  so called overlay organisation is implemented in the
Modula-2 system. It is a simple instrument to overlay
program parts.

An overlay part is a load  file,  produced  by  the  linker.
It consists  of  one  or  more  linked  modules. An overlay
part is loaded and executed, when it is called from that
base  part,  to which it has been linked (the base file).

This  simple  rule  allows  to  have program overlays on
several levels.

(**In the Modula-2 system the operating system is the first
overlay level.  All programs started via command interpreter
are running on the second overlay level. **)

Example : Storage layout by code during execution of a
          program

                                          storage
                     ------------------------------>
                     |     |
  B is called from A |     |-------------
                     |     |     B      |
  B is finished      |     |-------------
                     |     |
  C is called from A |     |--------
  D is called from C |     |       |------------
                     |     |       |           |
                     |  A  |       |     D     |
                     |     |       |           |
  D is finished      |     |   C   |------------
                     |     |       |
  E is called from C |     |       |--------
                     |     |       |   E   |
  E is finished      |     |       |--------
  C is finished      |     |--------
                     |     |



4.1.5C Call from a program:
--------------------------

If a program P2 is not linked to the basic  executive,  then
it must  be  called directly from the base part P1, to
which it has been linked, i.e.  the  procedure  Call,
exported  from  module Loader, must be activated (see
DEFINITION MODULE Loader).

4.1.5D Run time support for program management:
----------------------------------------------

Some functions for abnormal termination and for program
recovery are available from the module Exceptions.

(**If  P2  terminates  by  an  error,  then  it  is
recommended to propagate the error from P1 to the basic
executive  to  cause  a core  image dump and reinstallation
of the underlaying operating system (see DEFINITION MODULE
Exceptions).

Example : Fragments from module PROG4.

  VAR loadres : SystemTypes.LoadResultType;
      exerror : SystemTypes.ErrorType;

  ...

  Loader.Call("DK PROG5 LOD",loadres,exerror);
  IF exerror <> SystemTypes.NormalReturn THEN
    (* cancel execution *)
    Exceptions.PropagateError;
  ELSE
    ...
**)

(**
4.1.5E Converting from .LOD to .IMA format
------------------------------------------

The M3 utility program LODIMA allows to transform the .LOD
output file produced by the linker into a fast loadable
format .IMA (refer to 2.5).
**)

4.1.6. Debugging
----------------

If a run time error occurs and a program terminates
irregularly, then -if switched on- the Modula-2 system writes
the current image of the memory onto the dump file
DUMP.COR . This 'post mortem dump' can be inspected with
the debugger.



Starting the debugger
---------------------

To run the the debugger type    X DEBUG   in the CLE line.

The debugger first asks for two file names: the dump file and
the load file of the crashed program. Yyou may hit <RETURN>
twice and accept the defaults. For the dump file, the
default is DUMP.COR, and for the load file, it is the load
file name of the crashed program, taken from the dump file.
With the load file name, you may set the query or libquery
option to steer the access to the reference and source files.

The options which may be given with the load file name are:

/Q       query option. DEBUG should ask for the names of
         the reference and source files (REF and MOD)

/L       library query option. DEBUG should ask for the names
         of libraries to be searched for REF and MOD files.

When no options are given, then REF and MOD files are searched
automatically of the library of the load file.

Example:

->X DEBUG<cr>
 dump file> DUMP.COR
 crashed program XY:PROG1.LOD
 load file> XY:PROG1.LOD

    or

 load file> XY:PROG1.LOD/L
 libraries> A:,AB:


 ... generating P-chain

   Prog1.REF> XY:PROG1.REF<cr>


Files of the debugger
---------------------

The debugger needs the following files:
-  the dump file, DUMP.COR.
-  the load file of the crashed program
-  the .REF and the .MOD files of the modules to be debugged.

The dump file must be created explicitly be the user, otherwise 
no dumps can be taken.



Windows of the debugger
-----------------------

The debugger shows the crashed program through five windows (one at a time):

P(rocess window : shows the active procedures at the moment of the dump.
               Also, the procedure chains of other PROCESSes may be
               shown.

M(odule window : shows the list of all linked modules. After choosing a module,
               the T and D window will display data of the selected module rather
               than the procedure selected in the P window.

D(ata window : shows the value of the variables of the active procedures
               and the value of the global variables of the modules.
               Even local modules, structured variables and pointer
               chains may be inspected.

T(ext window : shows the source file, located at the point in error.
               For the T window, the debugger needs the source file
               and the reference file,
               which are searched or asked for (depending on options).
               Example:
                   PROG1.MOD> XY:PROG1.MOD <cr>

C(ore window : shows an absolute memory dump.



Commands of the debugger (DEBUG V1D)
------------------------------------

window switching commands:
            "P":  switch to P window
            "M":  switch to M window
            "D":  switch to D window
            "T":  switch to T window
            "C":  switch to C window
            "Q":  quit from debugger

window specific commands:

  P window: "@":  re-generate the P-chain of the process which
                  was running when the program was aborted

  M window: none

  D window: "S":  go to the son level (down)
            "F":  go back to the father level (up)
            "V":  go back to the last level with variables
            "A":  show address of the currently selected
                  data element
            "@":  generate the P-chain of the currently
                  selected variable or field of type
                  PROCESS or POINTER TO PROCESS, or of a
                  PROCESS variable specified by its address
                  and switch to the P window

  T window: none

  C window: "A":  ask for a new address and show its
                  environment in the core
            "@":  take the currently selected word as a new
                  address (indirect addressing)
            changing the data representation type:
                  "#C": CHAR
                  "#B": byte (octal)
                  "#W": WORD (octal, default)
                  "#I": INTEGER
                  "#U": CARDINAL (unsigned)
                  "#R": REAL


general commands (legal in all windows):

  change position:
            "+",<ESC>"B" (VT52/VT100 down arrow):
                  increment position
            "-",<ESC>"A" (VT52/VT100 up arrow):
                  decrement position
            "^":  increment position by half a screen length
            "_":  decrement position by half a screen length
         number:  set a new window position (line number)

  terminal: <ESC>"H": hardcopy terminal
            <ESC>"V": VT52/VT100 terminal (default)




4.1.7 Library Searching Strategies
---------------------------------- 

The following strategies are applied by the compiler and
linker to search the needed symbol or link files. The default
strategy or the query strategy can be chosen. Both strategies
refer by default to the default libraries (source or master
file directory, <empty> and MODLIB:).

A default name is generated from the module name. If the module
name is longer than 11 characters, then the first 11 characters
are taken for the file name  (SMAKY 8).

Default strategy
----------------

All  needed  files  are  searched by the default name (11
leading characters of the module name). A file is searched
in the same directory as the source/master file first. If this
search fails, then the file issearched on devices #MM0: and
MODLIB:.

For  each file a message is displayed, where is was found or
that it was not found. In the latter case the user has no
possibility to type another file name.

The libraries to be searched by the default strategy may
be changed for the compiler and the linker by the /L options.

Query strategy
--------------

For each searched file the user has to type a file name
(default device is <empty>).  If  search  fails,  then  an  error
message  is displayed  and  another file name must be
typed. If only <cr> is typed, then  the  file  is  searched
as in the default strategy.

Query  for  a  file  name is repeated until the file is
found or <esc> is typed. Typing <esc> means, that no file is
supplied.
On the SMAKY8, <esc> means the END key, <can> means the UNDO/ESC key.



4.1.8 The module SYSTEM
-----------------------

The module SYSTEM offers further tools of Modula-2.
Most of them  are  implementation  dependent  and/or  refer
to the given processor. Such kind of tools are sometimes
necessary for the so called  "low  level programming".
SYSTEM contains also types and procedures which allow a very
basic coroutine handling.

The module SYSTEM is directly known to the compiler, because
its exported objects obey special rules, that must be
checked by the compiler. If a compilation  unit  imports
objects  from  module SYSTEM, then no symbol file must be
supplied for this module.

Objects exported from module SYSTEM for this 68K Version:

Types
-----

WORD

Representation of an individually  accessible  storage  unit
(one word = 16 Bit on MC68000). No operations are allowed
for  variables  of  type  WORD, except assignment.  A  WORD
parameter  may  be substituted by an actual parameter of any
type that uses one
word in storage. If the parameter is a value parameter, then
values   of  types  using  one  byte  are  allowed  too  for
substitution. The same  holds  for  the  substitution  of  a
dynamic ARRAY OF WORD parameter by a value of a type with an
odd size.

ADDRESS

Byte address of  any  location  in  the  storage.  The  type
ADDRESS  is  compatible with all pointer types and is itself
defined as POINTER TO WORD. All cardinal arithmetic operators
apply to this type, as well as INC and DEC.
ADDRESS may be used in the sense of "long cardinal (32bit)".
The type ADDRESS is not compatible with the type CARDINAL.
Type transfer functions (zero-filling resp. truncating) have to
be used in mixed arithmetic expressions. 

Under the $T- option, INC and DEC are allowed for any pointer
variables, not only for ADDRESS.

PROCESS

Type used for process handling. (points to the (moving) top of
the process stack)


Procedures
----------

NEWPROCESS(p:PROC; a: ADDRESS; n: ADDRESS; VAR p1: PROCESS;
           ip: ADDRESS)

Procedure to instantiate a new process. At  least  300  words
are needed for the workspace of a process. ip is the initial
priority (optional, may be omitted. default is zero).

TRANSFER(VAR p1, p2: PROCESS)

Transfer of control between two processes.

IOTRANSFER(VAR p1, p2: PROCESS; va: ADDRESS)

Transfer  procedure  for processes operating on a peripheral
device. va is an interrupt vector address (not the vector
number).

LISTEN

Procedure  to  allow  an interrupt. The priority is set to 0
and afterwards back to the current priority.

SYSRESET

Procedure to initialise the system.

CODE(c: CARDINAL)

Procedure to allow the use of assembly code. c must be constant.

SETREG (r: CARDINAL; v: ....);

Procedure to set a register to a 32-bit value.
r = constant (0..7 = D0..D7, 8..15 = A0..A7).
v may be: a variable or constant (the value is put into the register),
or a procedure (the entry address is put into the register).

Functions
---------

ADR(variable): ADDRESS

Storage address of the substituted variable.

SIZE(variable): CARDINAL

Number  of  bytes  used  by  the substituted variable in the
storage. If the variable is of a record type with  variants,
then the variant with maximal size is assumed.
IF variable is not a dynamic array, then SIZE is compatible
to CARDINAL, INTEGER and ADDRESS (like a numerical constant).
If variable is a dynamicarray, then SIZE is compatible to
CARDINAL only (like a CARDINAL variable).

TSIZE(type): CARDINAL
TSIZE(type, tag1const, tag2const, ... ): CARDINAL

Number of bytes used by a variable of the  substituted  type
in  the storage. If the type is a record with variants, then
tag constants of the last FieldList  (see  Modula-2  syntax)
may  be substituted in their nesting order. If no or not all
tag constants are specified, then the remaining variant with
maximal size is assumed. TSIZE is compatible to CARDINAL,
INTEGER and ADDRESS (like a numerical constant).


REGISTER(num: CARDINAL): ADDRESS

Content of the specified register.
num must be a constant: 0..7 = D0..D7, 8..15 = A0..A7.
Register A5 points to the process descriptor record, A6
to the data of the current procedure (dynamic link),and
A7 to the top of stack.


function ASH (x, k):

shift x arithmetically by k bits. x may be CARDINAL, INTEGER, ADDRESS
or a set. ASH assumes the type of x.
k may be INTEGER or CARDINAL.  k>0 shifts left, k<0 shifts right.
k is only evaluated MOD 64.


BIT(i: CARDINAL OR INTEGER): BITSET;

Dynamic bit set function for {i}. i may be variable or constant.
(whereas in {i} of standard MODULA, i must be a constant;
only a procedure is provided for variable i (INCL)).



4.1.8A Workfiles
----------------

The compiler and the linker require workfiles, which can be
permanently on the disk. With a fixed disk, or with small programs
this is recommended. They should be created (MAKE) by the user when
installing Modula-2. Otherwise the compiler and linker will
create (and delete) them as required.

Debugging needs a dump file, where a memory dump can be written.
This file must be created explicitely (MAKE) by you when debugging
is desired.


File names and maximal file sizes:

      IL1.WORK        70 KB
      IL2.WORK        50 KB
      ASCII.WORK       9 KB
      LINKER.WORK     10 KB
      DEBUG.COR        memory size + 0.25 KB




4.1.8B Command File Execution
-----------------------------

On the SMAKY 8, command files are handled by the executive X, by
typing a file name with @, e.g.
     X @ORDERS
The file ORDERS.COM would then contain a list of programs to be run,
intermixed with the terminal input those programs expect.
Example for contents of ORDERS.COM (compile, link, execute ANYPROG):
     MODULA
     ANYPROG.MOD
     LINKER
     ANYPROG.LNK
     ANYPROG
     <eof>





4.1.8C History (Acknowledgements)
---------------------------------
This implementation is a combination and translation of the compilers
written by Leo Geissmann (PDP 11 Modula-2 compiler) and Hermann Seiler
(MC68000 code generation) .


4.1.9 Compiler error messages
-----------------------------

  0 :  illegal character
  1 :  eof in E+ option
  2 :  constant out of range
  3 :  open comment at end of file
  4 :  string terminator not in this line
  5 :  too many errors
  6 :  string too long
  7 :  too many identifiers (identifier table full)
  8 :  too many identifiers (hash table full)

 20 :  identifier expected
 21 :  INTEGER constant expected
 22 :  ']' expected
 23 :  ';' expected
 24 :  block name at the END does not match
 25 :  error in block
 26 :  ':=' expected
 27 :  error in expression
 28 :  THEN expected
 29 :  error in LOOP statement
 30 :  constant must not bee CARDINAL
 31 :  error in REPEAT statement
 32 :  UNTIL expected
 33 :  error in WHILE statement
 34 :  DO expected
 35 :  error in CASE statement
 36 :  OF expected
 37 :  ':' expected
 38 :  BEGIN expected
 39 :  error in WITH statement
 40 :  END expected
 41 :  ')' expected
 42 :  error in constant
 43 :  '=' expected
 44 :  error in TYPE declaration
 45 :  '(' expected
 46 :  MODULE expected
 47 :  QUALIFIED expected
 48 :  error in factor
 49 :  error in simple type
 50 :  ',' expected
 51 :  error in formal type
 52 :  error in statement sequence
 53 :  '.' expected
 54 :  export at global level not allowed
 55 :  body in definition module not allowed
 56 :  TO expected
 57 :  nested module in definition module not allowed
 58 :  '}' expected
 59 :  '..' expected
 60 :  error in FOR statement
 61 :  IMPORT expected

 70 :  identifier specified twice in importlist
 71 :  identifier not exported from qualifying module
 72 :  identifier declared twice
 73 :  identifier not declared
 74 :  type not declared
 75 :  identifier already declared in module environment
 76 :  dynamic array must not be value parameter
 77 :  too many nesting levels
 78 :  value of absolute address must be of type CARDINAL
 79 :  scope table overflow in compiler
 80 :  illegal priority
 81 :  definition module belonging to implementation  module
       not found
 82 :  structure  not  allowed  for implementation or hidden
       type
 83 :  procedure implementation different from definition
 84 :  not   all   defined   procedures   or   hidden  types
       implemented
 86 :  incompatible versions of symbolic modules

 88 :  function type is not scalar or basic type

 90 :  pointer-referenced type not declared
 91 :  tagfieldtype expected
 92 :  incompatible type of variant-constant
 93 :  constant used twice
 94 :  arithmetic error in evaluation of constant expression
 95 :  range not correct
 96 :  range only with scalar types
 97 :  type-incompatible constructor element
 98 :  element value out of bounds
 99 :  set-type identifier expected

101 :  undeclared identifier in export-list of the module

103 :  wrong class of identifier
104 :  no such module name found
105 :  module name expected
106 :  scalar type expected
107 :  set too large
108 :  type must not be INTEGER or CARDINAL or ADDRESS
109 :  scalar or subrange type expected
110 :  variant value out of bounds
111 :  illegal export from program module

120 :  incompatible types in conversion
121 :  this type is not expected
122 :  variable expected
123 :  incorrect constant
124 :  no procedure found for substitution
125 :  unsatisfying parameters of substituted procedure
126 :  set constant out of range
127 :  error in standard procedure parameters
128 :  type incompatibility
129 :  type identifier expected
130 :  type impossible to index
131 :  field not belonging to a record variable
132 :  too many parameters

134 :  reference not to a variable
135 :  illegal parameter substitution
136 :  constant expected
137 :  expected parameters
138 :  BOOLEAN type expected
139 :  scalar types expected
140 :  operation with incompatible type
141 :  only global procedure or function allowed in expression
142 :  incompatible element type
143 :  type incompatible operands
144 :  no selectors allowed for procedures
145 :  only function call allowed in expression
146 :  arrow not belonging to a pointer variable
147 :  standard function or procedure must not be assigned
148 :  constant not allowed as variant
149 :  SET type expected
150 :  illegal substitution to WORD parameter
151 :  EXIT only in LOOP
152 :  RETURN only in procedure or function
153 :  expression expected
154 :  expression not allowed
155 :  type of function expected
156 :  INTEGER constant expected
157 :  procedure call expected (or ':=' misspelled)
158 :  identifier not exported from qualifying module

161 :  call of procedure with lower priority not allowed

198 :  CARDINAL constant expected
199 :  BITSET type expected
200 :  size of structured type too large for this processor
201 :  array index too large for this element type
202 :  array element size too large for this processor
203 :  array index type too large for this processor
204 :  subrange too large for this processor

206 :  illegal subrange type
207 :  case label range too large, use IF statement
208 :  global data too large for this processor
209 :  local data too large for this processor
210 :  parameter data too large for this processor
211 :  offset of record field too large for this processor

225 :  too many unnamed types (typetable full)
226 :  reference file too long

300 :  index out of range
301 :  division by zero

303 :  CASE label defined twice
304 :  this constant is not allowed as case label

400 :  expression too complicated (register overflow)
401 :  expression too complicated (codetable overflow)
402 :  expression too complicated (branch too long)
403 :  expression too complicated (jumptable overflow)
404 :  too many globals, externals and calls
405 :  procedure or module body too long (codetable)

410 :  (UNIX only) no priority specification allowed
411 :  (UNIX only) global variable expected

923 :  standard procedure  or function not implemented
924 :  parameter must not be accessed with a WITH

940 :  compiler error, adr. cat. violation in PASS4
941 :  displacement overflow in ari addressing mode
942 :  32bit by 32bit multiply/divide not yet implemented
943 :  index range must not exceed positive integer range
944 :  jump too long (overflow in pc-relative offset)
945 :  offset too long (overflow in pc-relative offset)
946 :  FOR control variable is not of simple addressing mode

974 :  step 0 in FOR statement

981 :  constant out of legal range
982 :  overflow / underflow    in   index / offset / address
       calculation
983 :  use UNIXCALL instead of standard procedure call

990 :  too many WITH nested
991 :  CARDINAL divisor too large ( > 8000H )
992 :  FOR  control  variable  must  not have byte size (for
       step # -1, 1)
993 :  INC,  DEC  not  implemented with 2. argument for byte
       variable
994 :  too many nested procedures
995 :  FOR step too large ( > 7FFFH )
996 :  CASE label too large ( > 7FFFH )
997 :  type transfer function not implemented
998 :  FOR limit too large
999 :  missing symbol file(s)

